In This Topic

Structure of the Directory Certificate Store

As described in OPC UA Certificate Stores, directory certificate stores reside in a file system. In many cases, their structure can remain an opaque implementation detail to you. Knowing the structure comes handy if you need to deal with them externally or manually.

There are no files at the "root" of the directory certificate store, only sub-directories, and they are:

The "certs" subdirectory. Contains the certificates without private keys, in .DER format.
The "crl" subdirectory (only in certificate stores which need it). Contains the certificate revocation lists (CRLs) for the certificate store.
The "private" subdirectory (only in certificate stores which need it). Contains the certificate *with* private keys, in .PFX format. Instead of .PFX, it can also contain just the private key, in .PEM format (QuickOPC recognizes this but does not itself create files in directory certificate stores in this way).

If the certificate store contains a certificate with a private key, it will therefore be present in both "certs" and "private" subdirectories, each time in a different format.

The file name of each certificate comprises of the certificate common name (from its subject), followed by a space, and the certificate thumbprint in square brackets, e.g. "My Application [71511464F08D30AF9F9B2BC21CDB78D49BE568B8]". Special characters (like < > : " / \ | ? *) that cannot appear in file names are stripped off from the common name.

OPC Foundation has a UA Configuration Tool which can be used to manage the certificates related to OPC UA on Windows machines (both in the directory certificate stores, and in Windows certificate stores). QuickOPC includes this tool in the Bonus Material part of its full installation for Windows. You can access the UA Configuration Tool from the Start menu (under QuickOPC program group), or using the QuickOPC Launcher application.

Syntax of Directory Certificate Store Path

In its simplest form, the directory certificate store path is an absolute path to the directory that holds the store, e.g. "C:\ProgramData\OPC Foundation\CertificateStores\MachineDefault". Since absolute paths are not flexible enough and may fail to work when the application is transferred to a computer with different configuration, QuickOPC allows you to include replaceable tokens in the directory certificate store path. A token is enclosed in percentage sign characters, e.g. %CommonApplicationData%. For the token to be recognized, the directory certificate store path must begin directly with the token (the percent sign). Tokens are not recognized further down in the string.

The following two types of tokens can be used. QuickOPC searches for them from top to bottom.

Special folders. Any enumerated constant name from the .NET Environment.SpecialFolder enumeration (https://docs.microsoft.com/en-us/dotnet/api/system.environment.specialfolder ) can be used as a token. The token is replaced by the absolute path of the corresponding special folder. Not all available special folders make sense with OPC UA, but the following ones are good candidates: CommonApplicationData, CommonProgramFiles, ProgramFiles, etc.
Environment variables. These are the operating system environment variable names, as available to the current process. The value of the environment variable is retrieved, and replaces the token.
On .NET 6+ development platform only: "%LocalFolder%" (case sensitive). The current working directory of the application replaces the token. The string does not end with a backslash (\) or a slash (/).

If the token name is not recognized, the token is replaced by an empty string (i.e. the token is removed).

Platform Differences

The default certificate store paths have very different defaults in .NET Framework and .NET 6+.

In .NET Framework, the default certificate stores paths are "shared"; that is, by default, all applications developed with QuickOPC share the same certificate stores, which are system-wide.

In .NET 6+, the default certificate stores paths are all in directories that are located under the current working directory of the application.

In .NET Framework

When you target .NET Framework with QuickOPC, the default directory certificate store paths all start with the %CommonApplicationData% token, which on Windows typically resolves to something like "C:\ProgramData" (this is independent of whether your development target is .NET Framework or .NET 6+). Note: On Linux, the %CommonApplicationData% token typically resolves to "/usr/share", but that would only be of interest in .NET 6+ (see below), if you change the default store paths values.

In a default Windows installation, the "C:\ProgramData" directory exists, but it is hidden. You need to use appropriate setting or tool in order to be able to inspect the contents of hidden directories.

Example: The default application certificate store path is specified as "%CommonApplicationData%\OPC Foundation\CertificateStores\MachineDefault", and on Windows, it may resolve to "C:\ProgramData\OPC Foundation\CertificateStores\MachineDefault" (note that the "C:\ProgramData" folder is hidden).

In .NET 6+

When you target .NET 6+ with QuickOPC, the default directory certificate store paths all start with the %LocalFolder% token, which on resolves to the current working directory of the application.

Example: The default application certificate store path is specified as "LocalFolder/OPC Foundation/CertificateStores/MachineDefault". You will therefore have an "OPC Foundation" sub-directory in your current working directory, and a structure of the certificate stores below it.

Make sure you secure the directory certificate stores properly. This caution is particularly relevant with the default .NET 6+ settings, because you may end up with multiple certificate stores (directories) to be secured, not just the common "shared" one. Also note that the absence of the "shared" and commonly used certificate stores prevents certain inter-application cooperation scenarios from working, such as the practice that the OPC UA application stores its own application certificate to the trusted peers certificate store on the same machine, to make it easier for local connections to be established "out of the box".

Minimal Certificate Store Contents

For illustration, "minimal" directory certificate stores containing certificates for a single OPC UA application will typically look like this:

OPC Foundation
    CertificateStores
        MachineDefault
            certs
                <name and thumbprint>.der
            private
                <name and thumbprint>.pfx
        UA Applications
            certs
                <name and thumbprint>.der

Examples - OPC UA Administration

Examples - OPC Unified Architecture - Set application name for the client certificate

Examples - OPC Unified Architecture - Absolute directory paths for certificate stores